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abstract 

An artist acquires all the necessary tools before painting a 
scene. In the same analogy, a software engineer needs the necessary 
tools to provide his/her design with the proper means for 
implementation. Ada provides these tools. Yet, as an artist's 
painting needs a brochure to accompany it for further explanation 
of the scene, an Ada design also needs a document along with it to 
show the design in its detailed structure and hierarchial order. 

Ada could be self-explanatory in small programs not exceeding 
fifty lines of code in length. But, in a large environment, ranging 
from thousands of lines and above, Ada programs need to be well 
documented to be preserved and maintained. The language used to 
specify an Ada document is called Ada Structure Design Language 
(ASDL). This language sets some rules to help derive a well 
formatted Ada detailed design document. The rules are defined to 
meet the needs of a project manager, a maintenance team, a 
programmer and a system designer. This paper will explain in detail 
the design document templates, the document extractor, and the 
rules set forth by the Ada Structure Design Language. 


LJL Introduction 

Ada covers the different scopes under the software engineering 
spectrum. The Ada scopes can range from real time systems, 
scientific applications and other known software applications to 
abstract problems mapping, object oriented programming and new 
software engineering concepts. 

Keeping this in mind, Ada can become very complicated when 
designing large projects governed by many different tasks, generic 
entities and overloading mechanisms. Therefore, design documents 
are needed to clarify some of the obscurities that might arise when 
designing large systems. The design document should also accomodate 
for the tools provided by Ada and support the Ada language by 
showing the program, entities, and tasks at the functional level. 
The design method, called Ada Structure Design Language (ASDL), 
approaches Ada from two different levels : 
o The specification level, 
o The functional level. 
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ORIGINAL PAGE IS 
OF POOR QUALITY 


— <•««> 

— **** * ******** ** **************** * *** * * * ** *********** ********** * * * **** 

— * Package TASKS_INPUT_QUEUE * 

«... ****** *************** * * ** * ***** * * *** *** * ****** * ** ****** *** * * ** * ******* 

— <#•#> 


********************* ** ************** ** ** ***** * 


a 


* 

★ Author i 

Lutfl Chedrewi 

* 

ft Company t 

CSC 

* 

* Job order : 


* 

* Contract • i 


* 

a 


a 


— * *** * ** * *********************** **** * **** * * * * ** * ********************* 


with UNCHECKED J>EALLQCAT I ON j 


generic 

typ* OBJECT lft privatftf 
package TASKS_I NPUTJ3UEUE is 

— <••«> 


PACKAGE OMERVIEW 


— Package overview 


— Th# tasks input queue will manage the input queue for a given 

— process. The input queue manager task in this package will either 
— * put or take an object on or off the queue repectivcly. This task 

— also manages the queue by adding or releasing nodes to and from the 
— ■ input queue and keeping a record of the queue size. 


— Internal routines 


INTERNAL ROUTINES 
Description - 


— Ta«k 

— QUEUE J1ANAGER 


— Procedures 

— BET 

— PUT 

— QUEUE J8IZE 


To manage the queue size, the reads and wr tes 
from and to the input queue. In the read 
operation, if no objects were on the queue 
the queue manager requester will wait until 
an object is put on the queue. 

Performs a rendezvous with the get entry in 
the queue manager task to get an object off 
the queue. 

Performs a rendezvous with the put entry in 
the queue manager task to put an object on 
the queue. 

Performs e rendezvous with the queue size 
entry in the queue manager task to get the 
size of the queue in terms of number of nodes 
in the queue. 


Exceptions 


— N/A 


EXCEPTIONS 


Description 


totGIN AL p 
W Poo « 
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■•■•■■■■■•■■■■■■■■•■■•■■■•■■■■■•■■••■■■•■■■•■a 

EXTERNAL REFERENCES 

— External entities — 

Description 

— N/A. 
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EXTERNAL ROUTINES 

— External routines — 

Descr i p t i on — — — ■ — 

— Procedure 

— UNCHECKED 

.DEALLOCATION 

This procedure will release the input queue 


nodes back to heap storage. 


CHANGE HISTORY 


— Date/Authors — 

— 3/31/BE 

- Lutfi 

— 4/1/86 

- Lutfi 

— 4/1/86 

- Lutfi 


Description — — - - — — 


Added a get procedure to rendezvous with the 
got on try in the input queue manager t««i. 
Added a put procedure to rendezvous with the 
put entry in the input queue manager task. 
Added a queue size procedure to rendezvous 
with the queue size entry in the input queue 
manager task . 



— 


DEPENDENCY TREE 




Dependency tree 


Task Calling procedures 

QUEUE _JiANAGER — 


Eft cr i es I 

o GET I GET 

• PUT I 

o QUEUE.SIZE t 

I PUT 

I 

I 

l_ QUEUE.8IZE 


— <•##> 

— QUEUE — > to queue the request for a task in a FIFO queue, 
type QUEUE f 

type QUEUE.ACCESS is access QUEUE | 
type QUEUE is 
record 

FORWARD l QUEUE. ACCESS | 

BACKWARD l QUEUE.ACCESS | 

ELEMENT i OBJECT | 

end recordi 

— Internal routines GET, PUT and QUEUE.SIZE 

procedure GET (ELEMENT i out OBJECT )f 

procedure PUT (ELEMENT I in OBJECT )| 

procedure QUEUE.SIZE (SIZE_OF_QUEU£ t out INTEGER ) | 

end TASK9_INPUT_0UEUEf 

Example -1* i Ada specification level design document using ASDL. 
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5.0 ASDL levels: 


5.1 - The specification level; 

ASDL, at this level, will suffice the specification definition 
and description of a system and put the following at hands : 
o Requirements : statement definition of the overall 

structure . 


o Author ft 

History updates : a log file of updates will provide another 

programmer and the system manager with 
history information of all changes made. 
This pin-points the responsible person for 
the changes made and keep track of program 
progression. 

Tracking responsibilities is needed by the 
system manager in case any ambiguities ever 
arise that need further explanation or 
further documentation to help clarify the 
changes made. 

o Independability : interfaces and hierarchies definitions of 

each entity . 

o Maintainability : the system will be easily maintained 

throughout its life cycle. ASDL will 
provide all the clues for a maintenance 
team to keep track of the environment. 


5.5 The functional level : 

ASDL, at this level, provides programmers with tools for 
debugging ease and managers with prospects on design clarity It 

allows, the documentation of : 

o Requirements : statement definition of an entity, 
o Structured 

analysis : explaining the input/output and 

specifications of each entity. 

o Structured 

design : defining the functional flow of each 

entity . 


3.0 ASOL format 

3.1 ASDL specification, level format; 

ASOL will show the declaration of an entity. The data structure, 
functions, procedures, tasks, and packages are explained at this 
level in a general form without going into details. The 

specification level design document using ASDL is shown in example 
-1-. A further investigation of this example allows us to identify 
different entries within the specification level format. Each entry 
permits the documentation of a part of the system that meets the 
needs of the different classes of people involved. All entries are 
mapped to a static form which allows the derivation of a 
specification level template. The template skeleton is static on 
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the outside, but the explsnation within each entry can be 
dynamically filled with information to preserve the creator’s 
integrity to express his own design documents. 

The template entries for the specification level format serve as 
a road map to each or all individuals involved in the design of the 
entity. ASDL specification template format holds the following 
entries: 

o entity overview 
o internal routines 
o exceptions 
o external references 
o external routines 
o change history 
o dependency tree 

The entity overview entry identifies the function of an entity. 
This entry serves all the classes of people involved in the 
development of the project. The information covered in this entry 
should hold the important features governining an entity . Not only 
would this entry serve as information coverage of the entity but 
also acts as a fast index to the contents of the entity under 
development or investigation. 

The internal routines entry covers the naming definitions and the 
entity internal routines descriptions. A maintenance team can make 
use of this entry by utilizing the explanation provided to 
understand the problem statement definition and to identify the 
internal routines. Both, the project developers and system 
maintainers hold the responsibility of keeping the information 
within this entry up to date. 

The exceptions, external references and external routines entries 
exclusively permit the system designers and project managers to 
recognize the system exceptions handling mechanism and to 
understand the system components interaction. The system designers 
can keep a close watch of the system by making sure that all errors 
are handled and a safe passage is assured by the exceptions 
handlers. Moreover, the exception entry will provide a fast summary 
of all exceptions occuring within an entity. In the same manner, 
the external references and routine entries will allow the project 
managers to check the entity interaction at both the general 
CExternal references! and specific levels (external 
references’ internal routines.! 

The history changes entry, allows the system maintainors to log 
all the changes made to the entity throughout its life cycle. 
Moreover the system developers can communicate among each other by 
notifying through this entry other team members of important 
changes . 

The tree dependency nicely shows in a graphic form the entity 
internal hierarchy. This entry is intended to serve all the people 
Involved in the project. 
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ORIGINAL PAGE IS 
OF POOR QUALITY 


pack age body TASKS_INPUT_QUEUE I » 

procedure DEALLOCATE is now UNCHEKED_DEALLQCAT 1 ON (QUEUE, QUEUE.ACCESS) | 

— Input quaua managor — > will r«tr«ivt information from tha input 

— quaua 

task typo 1 NPUT_QUEUE JMANA6ER is 

on try PUT (ELEMENT i in OBJECT )j 

on try GET (ELEMENT 1 out OBJECT )j 

ontry QUEUE_SIZE (S1ZE_0FJJUEUE i out INTEGER )| 

and) 

QUEUE _MPNAGER i INPUTJ3UEUE_MPNAGER \ 


pra^na PAGE \ 

— <♦♦♦> 

took body INPUT_QUEUEJ1ANAGER is 

— SIZE -> to raturn tha siza of tha input quaua in tarns of numbar 
— of nodas in tha quaua. 

SIZE i natural i» Oj 


— Function t to managa tha input quaua. It ai thar puts on or takas 

— an objact off tha quaua. Tha GET antry to gat an objact 

— off tha quaua is guardad so tha task will mako tha 

— raquastor wait until an objact is put on tha quaua. 

— This task will managa tha quaua siza and raturn its 

— valua whan raquastad. 

— In i N/A 


— In Out i N/A 


— Out t N/A 



ALGOR ITHi 


— Algorithm i 

— bag in 

— loop 

— select 

— whan siza is graatar than zaro. 

— accapt gat (alamant i out obiact) do 

— gat out obi act from tha noda at tha forward link of haad 

— of tha quaua 

— sat tha forward link of tha noda at tha gat noda's backward 

— link to tha forward link of tha gat noda. 

— sat tha backward link of tha noda at tha gat noda's forward 

— link to tha backward link of tha gat noda. 

— ralaasa gat noda back to haap storaga 

— dacromant siza 

— and gatf 

— or 

— accapt put (alamant t in object) do 

— craata now noda 

— insert •in* object 

— sat naw noda forward link to haad of tha quaua 

— sat naw noda backward link to haad backward link 

~ sat forward link of tha noda at tha haad backward 

— link to naw noda 

— sat backward link of haad to naw noda 

— tncromo n t siza 

— and put | 
or 

-- accapt queue_size ( si ze_of_queue t out integer) do 

— sat siza_ 0 f_Quaua to siza 

— and queue_*izei 

— and salacti 

— and loop) 

— and input quaua manager j 

— <**•> 
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ORIGINAL FAQ 

Of POOR QUALITY 

( ELEMENT t out OBJECT ) is 

— Function t to coll tho input queue manager task to it can got an 

— object off tho queue. 

— In i N/A 

— In Out t N/A 

— Out i element -> tho object to bo returned from the queue. 



— <#*•> 

end TASKS_INPUT_QUEUE | 

Example “2- t Ada functional level design document using ASOL. 


pragma PAGE i 

— <•♦•> 

procedure GET 
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3-ug 3SBL functional laval format; 

ASDL will describe the system in a more detailed functional flow. 
ASDL will require system developers to combine Ada keywords and the 
english language to bring about a detailed flow of the entity, yet 
not cryptic to the designers or software maintainors. The system 
manager can also check the system logic and design structure for 
ambiguity, clarity, performance and possible implementation (i.e 
whether the entity can be implemented as described or whether the 
implementation is not possible due to misinterpretation of problem 
definition, requirements need, Ada weaknesses, etc....). 

ASDL functional level format holds four entries as shown in 
example -S-. The "in", ”in out” and "out” entries correspond to Ada 
parameters passing descriptions. The inclusion of these entries 
will entitle the system maintainors, developers, designers and 
managers to understand the input/output of system components. 
Moreover, a functional flow design is given by the algorithm entry 
to show the structure in its more detailed english like design. 

Finally, ASDL tends to be similar to POL (Process Design 
Language) at this level, which proves to be advantageous since no 
training is needed for individuals already familiar with PDL. 


4.0 ASDL rules 

4.1 ASDL specification level rules: 

In general, ASDL does not impose any rigid rules. The ASDL rules 
for the specification level format should insure the derivation of 
a design document. The rules are set to give a detailed explanation 
of entities interactions, entity specification and data 
representation. The specification level format can be mapped onto 
the following rules : 

o new updates should be entered when necessary 

o dependency tree should be leveled to show the new entities in 
their hierarchial depth 

o history logs updates should cover the changes made 
o the information should be entered under the specified field 
to insure the extractor ability to perform its functions. 

4.5 ASDL functional level rules : 

At this level, ASDL requires developers to respect the outer and 
inner structures of Ada blocks, statements and looping mechanisms. 
The Ada keywords should be entered to show the Ada flow as if it 
was coded. Moreover, the Ada keywords should be combined with a 
detailed explanation in english to show the flow of Ada statements. 
The advantages of combining Ada keywords and english words will 
divulge when the implementation phase takes place. The project’s 
implementation will become a matter of mapping the algorithm to Ada 
code. 
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5.0 ASDL extractor 


5.1 The formatter extractor: 

ASDL extractor is envisioned as a formatter extractor with menu 
driven options. Uhen asked to format a document written by ASDL, 
the extractor will prompt the requestor with a menu. The menu 
selection can be accessed through cursor control . 

ASDL formatter extractor should come with default values to allow 
simple extracting and echo printing of text to the specified 
destination file. On the other hand, if required, the extractor 
should perform all the necessary tasks to derive a well formatted 
Ada design document including centering of titles, margin 
Justification, page numbering and other functions found in 
wordprocessors . Moreover, the extractor can control the part of 
text to be extracted from the document by a simple turn on/off 
flags or toggle keys Cif an interactive session is requested.) 
Those flags are shown in example 1 ft S as *0’, signs preceded 
and succeded by ’ < * and ’ > ’ designators . 


6.0 Conclusion 

In summary, ASDL will prolongs the software life cycle. In 
addition, it will allow the documentation of large systems 
otherwise might become very difficult to understand. Finally, ASDL 
will act as a communicae to all the classes of individuals involved 
in the system development. 


* Ada is a registered trademark of the U.S government, Ada Joint 
Program office. 

* ASDL extractor is still under development. 
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